Voicemod Discord Bot — Documentation

Documentation

Learn how to install, configure, and extend the Voicemod Discord Bot. This guide covers setup, commands, the WebSocket control API, soundboard/voice customization, permissions, and troubleshooting.

Start Here

Overview

The bot connects Discord to your local Voicemod app through a persistent WebSocket, enabling near‑instant voice switching, soundboard playback, and effect tweaks. Use slash commands for structured control and optional role checks to keep usage secure.

  • Low-latency control
    Persistent WS keeps actions instant.
  • Rich customization
    Adjust EQ, mix, clarity, and more.
  • Role-gated
    Limit who can run sensitive actions.

Getting Started

Follow these steps to get up and running.

  1. 1
    Install Voicemod
    Download and install Voicemod, then select it as your microphone in your voice apps.
  2. 2
    Invite or run the bot
    Use the OAuth invite for hosted version, or self-host using the Discord Developer Portal.
  3. 3
    Connect to local Control API
    Ensure the bot can reach the localhost WebSocket endpoint. Test with /status.
Prerequisites
  • Windows fully supported. On macOS, verify Voicemod support and routing.
  • Allow localhost (127.0.0.1) communication in your firewall.
  • Keep Voicemod open while using the bot.

Commands Reference

slash + text
Change Voice
Switch the active preset immediately.
/voice robot/voice cave!voice custom-1
Play Sounds
Play soundboard clips; supports overlap and loops.
/sound airhorn/sound loop:rain!s meme.wav
Effect Parameters
EQ, clarity, noise reduction.
/eq bass:6 mid:-1 treb:3/clarity 80/noisegate on
Feature Toggles
Control key Voicemod features.
/toggle voicechanger/toggle hearmyself/ambient off
Help & Status
List commands and check connection health.
/help/status

Voice & Soundboard Customization

Fine‑tune how your voice and sounds behave using parameters.

EQ & Clarity
Examples:
{
  "action": "SET_EQ",
  "payload": { "bass": 6, "mid": -1, "treble": 3 }
}
Command: /eq bass:6 mid:-1 treb:3, /clarity 80
Soundboard Controls
  • Play once: /sound airhorn
  • Loop: /sound loop:rain
  • Stop all: /sound stop
{
  "action": "PLAY_SOUND",
  "payload": { "name": "airhorn", "loop": false }
}

WebSocket Control API

JSON

The bot maintains a persistent WebSocket with your local Voicemod app. Messages are structured with action, id, and payload fields.

Message Format
{
  "action": "SET_VOICE",
  "id": "req-1842",
  "payload": {
    "voiceId": "robot",
    "params": {
      "mix": 0.85,
      "clarity": 0.7,
      "eq": { "bass": 6, "mid": -1, "treble": 3 }
    }
  }
}
Responses include ok/error and the matching id.
Common Actions
  • SET_VOICE — Change active voice preset.
  • PLAY_SOUND — Trigger soundboard audio.
  • SET_EQ — Adjust EQ bands.
  • TOGGLE_FEATURE — Enable/disable app features.
  • PING — Health checks.

Permissions & Role-Based Access

Restrict commands to trusted roles. Define allowlists for actions like toggles and volume changes.

Role Checks
Gate sensitive commands to roles like @DJ or @Mods.
Granular Controls
Separate permissions for /sound, /toggle, and /eq.
Audit & Logging
Log who invoked what for transparency and debugging.

Troubleshooting & FAQ

help
  • /status shows disconnected
    Ensure Voicemod is running and the local WebSocket endpoint is reachable on localhost.
  • No sound is heard
    Verify chain: Mic → Voicemod → Discord/Streaming app. Check input/output routing.
  • Permission denied
    Confirm the invoking user has the required role or update the bot’s role configuration.